10.1 Filtering Items

Todo mode provides three ways to filter items: a general filter for items matching a user-entered regular expression, as with the search command; and two specific filters, one for diary-displayable items (i.e., those lacking todo-nondiary-marker) and one for top priority items (more on the latter below). The commands for each filter come in pairs, one for filtering just the current todo file and one for filtering a user-specified list of todo files. Thus, there are six item filtering commands:⁹

• F x x (todo-filter-regexp-items)
• F x m (todo-filter-regexp-items-multifile)
• F y y (todo-filter-diary-items)
• F y m (todo-filter-diary-items-multifile)
• F t t (todo-filter-top-priorities)
• F t m (todo-filter-top-priorities-multifile)

There are two ways to specify which files the multifile filtering commands apply to. If there are files you want to filter every time you use these commands, customize the option todo-filter-files. If you leave this option empty (the default), invoking a multifile filtering command pops up a buffer similar to the Customization buffer for todo-filter-files, in which you can select files to filter just for this invocation.

Diary and top priority items are by definition non-done todo items, but when filtering by regular expression, you can extend the scope of the command to done items by enabling the option todo-filter-done-items. Then F x x and F x m will gather both matching todo and matching done items (including done items from any archive files corresponding to the selected todo files) into the virtual category of filtered items.

There are several ways to specify how many items in each category count as top priorities and hence get filtered by F t t and F t m:

• The option todo-top-priorities specifies a single default number for all categories and all todo files; its default value is 1, which means just the highest priority item in every category is filtered, unless otherwise specified.
• The option todo-top-priorities-overrides lists file-wide overrides of todo-top-priorities as well as category-specific overrides. It is empty by default. However, using the Custom facility to set this option would be tedious and error-prone, so instead you should use the commands F t s and C t s. The former sets (i.e., overrides) the default number of top priorities for all categories in the current todo file, and the latter sets the number of top priorities for the current category. To exclude a category or file from filtering by F t t and F t m, set the number to ‘0’.
• You can invoke F t t and F t m with a numeric prefix argument, which specifies the number of top priorities in each category just for this invocation, overriding both todo-top-priorities-overrides and todo-top-priorities.